home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 23 / AMIGAplus Sonderheft 23 (2000)(Falke)(DE)[!].iso / Updates / Librarys / MMULib / Autodocs / memory.doc < prev    next >
Text File  |  1999-11-19  |  15KB  |  489 lines
  1. TABLE OF CONTENTS
  2.  
  3. memory.library/--Background--
  4. memory.library/CreateAdrSpace
  5. memory.library/DeleteAdrSpace
  6. memory.library/AllocVMPool
  7. memory.library/DeleteVMPool
  8. memory.library/AttachTask
  9. memory.library/DetachTask
  10. memory.library/AllocVMVec
  11. memory.library/FreeVMVec
  12. memory.library/LockVMVec
  13. memory.library/UnlockVMVec
  14. memory.library/--Background--                    memory.library/--Background--
  15.  
  16.     PURPOSE
  17.         The memory.library provides functions for memory allocation and
  18.         deallocation that are superior to those of the exec.library.
  19.  
  20.         The functions of this library will provide so called "virtual memory"
  21.         by using the mmu.library, memory that can be swapped to disk
  22.         transparently to the application. Hence, applications will be usually
  23.         able to allocate more memory than physically available.
  24.  
  25.         Certain access restrictions arise for memory allocated by the
  26.         memory.library. First, you can't access it in Forbid() or Disable()
  27.         state. Second, it can't be shared amongst different pools. You
  28.         must explicitly attach the tasks that should be able to access memory
  29.         from a given pool. Thus, you can't use this kind of memory for keeping
  30.         Os structures since they may be passed to different tasks for further
  31.         processing. Third, you MAY NOT access virtual memory in a situation
  32.         where file I/O would be impossible. That is, DO NOT access this mem
  33.         while:
  34.             - holding a lock on the dos.library handler lists
  35.             - disabling the filing system of the swap partition
  36.             - making the swapping exec.device unaccessible
  37.             - taking over the hardware
  38.         The mmu.library will try to detect such situations and will throw
  39.         a guru if that's possible. However, if it is not, these situations
  40.         will result in a dead-lock! Keep care!
  41.     
  42.  
  43.         This restriction can be somewhat weakened by the LockVMVec/UnlockVMVec
  44.         functions. By calling these functions, you can lock a given memory
  45.         vector in memory and hence, will be able access it WITHIN Forbid().
  46.         It returns a pointer to the physical location of that memory block
  47.         which must be used if that memory is passed to a different task or
  48.         other hardware components.
  49.  
  50.         This kind of "virtual memory" is of course some kind of a 
  51.         "poor man's solution" for implementing virtual memory. No exec
  52.         function will be patched and old programs will continue to work
  53.         without any change. The library is of course of limited or no use
  54.         at all for old programs since it doesn't redirect standard memory
  55.         allocation functions to their "virtual" counterparts. Thus, this
  56.         is a very "conservative" approach to overcome this limitation of
  57.         AmigaOs.
  58.  
  59.         A special "VMM/GigaMem" patch might be made available that uses
  60.         the functions of this library to provide virtual memory to every
  61.         task. However, since this CAN'T be fully compatible to old programs
  62.         and may, therefore, cause some compatibility problems. It should be
  63.         up to the user if she/he likes to install a patch like this or not,
  64.         but it should NOT the way how virtual memory enters AmigaOs, at 
  65.         least not now.
  66.  
  67.         The basic objects the memory.library handles is first the
  68.         "AddressSpace" object. It defines - as it says - an common 
  69.         address space for the tasks attachted to it. It is the memory.library
  70.         implementation of the mmu.library "context". Each address space can
  71.         be linked to as many tasks as you wish, but a task can be attached
  72.         to only one address space at a time.
  73.         The actual memory allocation is done from "VMPools". They are the
  74.         memory.library counterpart of the exec "memory pools". Each address
  75.         space may contain as many "VMPools" as you wish, but only tasks
  76.         attachted to the address space of the pool can use it.
  77. memory.library/CreateAdrSpace                    memory.library/CreateAdrSpace
  78.  
  79.     NAME
  80.         CreateAdrSpace    -    create a new address space.
  81.  
  82.     SYNOPSIS
  83.         BOOL CreateAdrSpace( );
  84.         d0
  85.  
  86.         BOOL CreateAdrSpace( VOID );
  87.  
  88.     FUNCTION
  89.         Build a new address space and attach the calling task to this
  90.         address space. 
  91.  
  92.     INPUTS
  93.         none.
  94.  
  95.     RETURNS
  96.         a true/false boolean success indicator.
  97.  
  98.     NOTES
  99.         This call will build a new mmu.library "Context" for the calling
  100.         task and will enter this context for this task. The task calling
  101.         this function should not be attachted to any other address space
  102.         or this task will fail. A task can be attached to one address 
  103.         space at a time only.
  104.  
  105.         This call will change the tc_Switch() and tc_Launch() function
  106.         pointers of the calling task.
  107.  
  108.     SEE ALSO
  109.         DeleteAdrSpace(), exec/tasks.h
  110.  
  111. memory.library/DeleteAdrSpace                    memory.library/DeleteAdrSpace
  112.  
  113.     NAME
  114.         DeleteAdrSpace    -    delete an address space.
  115.  
  116.     SYNOPSIS
  117.         DeleteAdrSpace( );
  118.  
  119.         DeleteAdrSpace( void );
  120.  
  121.     FUNCTION
  122.         This call deletes the address space of the calling task. It will
  123.         leave the private context build for this address space and will
  124.         enter the global context.
  125.  
  126.     INPUTS
  127.         none.
  128.  
  129.     RETURNS
  130.         nothing.
  131.  
  132.     NOTES
  133.         This call uses the CurrentContext() call of the mmu.library and
  134.         deletes this context. The task is then re-attachted to the global
  135.         common context. No virtual memory must be used at that time, nor
  136.         any other task may be attachted to this address space.
  137.  
  138.         It is safe to call this function if the calling task isn't attached
  139.         to any address space. Nothing will happen in this case.
  140.  
  141.     SEE ALSO
  142.         CreateAdrSpace(), mmu.library/CurrentContext()
  143.  
  144. memory.library/AllocVMPool                            memory.library/AllocVMPool
  145.  
  146.     NAME
  147.         AllocVMPool    -    create a pool of virtual memory.
  148.  
  149.     SYNOPSIS
  150.         pool = AllocVMPool( reqments, attributes );
  151.         d0                    d0          d1
  152.  
  153.         VMPool * AllocVMPool( ULONG, ULONG );
  154.  
  155.     FUNCTION
  156.         Creates a memory pool for virtual memory and adds the calling task
  157.         to the list of tasks that can safely use this pool.
  158.  
  159.     INPUTS
  160.         reqments    -    an exec style memory attributes flags field.
  161.                 This defines the memory type the pool will be taken from,
  162.                 not ANY implications about the logical addresses asssigned
  163.                 to the memory allocated from that pool. Thus, if you call
  164.                 LockVMVec() later on, that vector will be mapped to the
  165.                 memory described by the reqments above.
  166.  
  167.                 The following bits, defined in exec/memory.h will be 
  168.                 ignored:
  169.  
  170.                 MEMF_PUBLIC        -    as the pool is always private in 
  171.                     this sense.
  172.  
  173.                 MEMF_CLEAR        -    as this flag must be specified 
  174.                     individually when allocating memory from the pool.
  175.  
  176.         attributes    -    special attribute flags.
  177.  
  178.                 VMEMF_PRIVATE    -    make the memory in the pool invalid
  179.                     to other tasks.
  180.  
  181.                 VMEMF_PROTECT    -    protect the underlying MMU context.
  182.  
  183.                 VMEMF_NONCACHE    -    mark the memory in the pool 
  184.                     explicitly as noncacheable 
  185.                     (defaults to the cache type of the physical memory)
  186.  
  187.                 VMEMF_PRECISE    -    mark the memory in the pool as
  188.                     requiring the precise exception model.
  189.                     (only for special MMUs, not available in general)
  190.                     Implies VMEMF_NONCACHE
  191.  
  192.                 VMEMF_SERIALIZED-    mark the memory as serialized non-
  193.                     cacheable.
  194.                     (only for special MMUs, not available in general).
  195.  
  196.         RETURNS
  197.             A handle to the pool or NULL in case of failure. The calling
  198.             task will be prepared to use the memory in the pool.
  199.  
  200.         NOTES
  201.             To use this call, a private address context must have been
  202.             build before.
  203.  
  204.         SEE ALSO
  205.             CreateAdrSpace(), DeleteVMPool(), exec/memory.h
  206.                 
  207. memory.library/DeleteVMPool                        memory.library/DeleteVMPool
  208.  
  209.     NAME
  210.         DeleteVMPool    -    Delete a virtual memory pool.
  211.  
  212.     SYNOPSIS
  213.         result    =    DeleteVMPool( pool);
  214.         d0                          a0
  215.  
  216.         BOOL DeleteVMPool (VMPool *);
  217.  
  218.     FUNCTION
  219.         Deletes the given virtual memory pool in question, releases the
  220.         memory occupied by the pool and the release the used space on disk.
  221.  
  222.     INPUTS
  223.         pool    -    a handle to a VMPool as created by AllocVMPool. 
  224.             Passing in NULL is safe.
  225.  
  226.     RESULTS
  227.         A boolean that indicates whether some memory in the pool is
  228.         still allocated. Can be usually ignored but is useful for
  229.         debugging.
  230.  
  231.     NOTES
  232.  
  233.     SEE ALSO
  234.         AllocVMPool()
  235.  
  236. memory.library/AttachTask                            memory.library/AttachTask
  237.  
  238.     NAME
  239.         AttachTask - attach a task to the address space of the calling task.
  240.  
  241.  
  242.     SYNOPSIS
  243.         result = AttachTask( task);
  244.         d0                     a1
  245.  
  246.         BOOL AttachTask(struct Task *);
  247.  
  248.     FUNCTION
  249.         To allow another task sharing the same address space than the calling
  250.         task, this new task must be attached to the common address space
  251.         with this call.